[material-ui][docs] Add deprecations migration guide #40767

DiegoAndai · 2024-01-23T18:52:21Z

Part of: #40417

This PR adds the migration guide for current deprecations.

The idea is for this to be a "living" document:

Whenever we add a deprecation, an example is added to this migration guide as well to provide clarity
When a deprecation turns into a breaking change in a major version release, the example is moved to that version's migration guide

Preview: https://deploy-preview-40767--material-ui.netlify.app/material-ui/migration/migrating-from-deprecated-apis

mui-bot · 2024-01-23T18:54:37Z

Netlify deploy preview

docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 46623cb

samuelsycamore

Maybe we should add a callout in the Accordion demo doc as well? If you're using the deprecated APIs and you land on that page, you'll be confused when you can't find any mention of them in the Transition section.

docs/data/material/migration/migrating-deprecations/migrating-deprecations.md

Co-authored-by: Sam Sycamore <[email protected]> Signed-off-by: Diego Andai <[email protected]>

DiegoAndai · 2024-01-31T18:32:35Z

Hey @samuelsycamore, thanks for the review! I appreciate it 😊

The only ones I didn't apply:

I think the codemod link is necessary because:
- I expect this doc to grow fast. Take a look at this list 😅: [material-ui] Standardize slots pattern and composed classes #40417
- Users might want to run the specific codemod. We could have the command on the docs, duplicating the deprecations' README. It's better to link to it. The content is indeed similar but slightly different:
  - The doc is organized per deprecation to show atomic examples
  - The source is organized per codemod; there will probably be a relation of 1:N from codemod to deprecations
I would add another warning to the transitions demo. If users are using the deprecated props, they can find information on the API page. I want to avoid deprecation warnings on the demos; those are better suited to the API page. If we start getting issues about it, we can reconsider.

Question: How do I fix the "Use a non-breaking space for brand name ('Material UI' instead of 'Material UI')" review dog issue?

danilo-leal · 2024-02-01T03:33:02Z

Question: How do I fix the "Use a non-breaking space for brand name ('Material UI' instead of 'Material UI')" review dog issue?

Through trial & error on #40403, I've found that using, e.g., Material UI, seems to make Vale happy for that. :)

samuelsycamore · 2024-02-01T14:58:27Z

@danilo-leal @DiegoAndai I could be wrong, but I believe it also works if you type a non-breaking space " " using shift + option + space (if you're on a Mac), which seems to be how the Vale rule is written, and makes it a little less ugly in the Markdown doc. cc @oliviertassinari who added this rule recently to confirm.

danilo-leal · 2024-02-01T15:00:17Z

Ah, cool — didn't know about this shortcut; appreciate it! Might be worth adding it to the style guide :)

samuelsycamore · 2024-02-01T15:00:52Z

Yes good idea! I imagine this is going to trip people up for awhile.

samuelsycamore

tentatively approving before those pesky non-breaking spaces are added 😁

oliviertassinari

Question: How do I fix the "Use a non-breaking space for brand name ('Material UI' instead of 'Material UI')" review dog issue?

cc @oliviertassinari who added this rule recently to confirm.

I use option⌥ + space to generate a nonbreaking space. We were using Material-UI in the past to solve this problem, but we changed the name in https://mui.com/blog/material-ui-is-now-mui/. This error comes from #40525. Material UI is a great option in JSX. For markdown, I'm not a fan, harder to read.

oliviertassinari · 2024-02-06T21:24:37Z

docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md

+-    TransitionComponent={CustomTransition}
+    slots={{ transition: CustomTransition }}


I think we should follow the git diff format with our syntax connections (two space tab):

Suggested change

- TransitionComponent={CustomTransition}

+ slots={{ transition: CustomTransition }}

- TransitionComponent={CustomTransition}

+ slots={{ transition: CustomTransition }}

x the other cases

oliviertassinari · 2024-02-06T21:25:31Z

docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md

+
+### TransitionProps
+
+The Accordion's `TransitionProps` was deprecated in favor of `slotProps.transition` ([Codemod](https://github.com/mui/material-ui/tree/master/packages/mui-codemod#accordion-props)):


I think we should link to the default branch here so it continue to work even when we are on v6 next branch

Suggested change

The Accordion's `TransitionProps` was deprecated in favor of `slotProps.transition` ([Codemod](https://github.com/mui/material-ui/tree/master/packages/mui-codemod#accordion-props)):

The Accordion's `TransitionProps` was deprecated in favor of `slotProps.transition` ([Codemod](https://github.com/mui/material-ui/tree/HEAD/packages/mui-codemod#accordion-props)):

x the other cases

oliviertassinari · 2024-02-06T22:14:19Z

docs/pages/material-ui/migration/migrating-from-deprecated-APIs.js

+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from 'docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs {...pageProps} />;
+}


The file pathname casing is wrong

Actual: docs/pages/material-ui/migration/migrating-from-deprecated-APIs.js
Expected: docs/pages/material-ui/migration/migrating-from-deprecated-apis.js

it leads to two bugs:

Side nav not expanded (why I looked in the first place, seemed strange):

Console errors:

Can we fix it? :)

oliviertassinari

Great to have this page 👍

oliviertassinari · 2024-02-06T22:21:04Z

docs/data/material/migration/migrating-from-deprecated-apis/migrating-from-deprecated-apis.md

+
+### TransitionComponent
+
+The Accordion's `TransitionComponent` was deprecated in favor of `slots.transition` ([Codemod](https://github.com/mui/material-ui/tree/master/packages/mui-codemod#accordion-props)):


I think that we should explain why we are making each deprecation. The very first thing as I developer I would want to understand is why am I going through this pain, what do I get? For example, https://mui.com/material-ui/migration/migration-v3/ illustrates this, we tried to justify why each breaking change.

Yes! We have two overarching deprecation initiatives: standardizing the slots pattern and removing composed classes. I considered adding an explanation of those and then linking accordingly in each deprecation. Would that make sense?

DiegoAndai · 2024-02-07T13:24:37Z

Thanks for the catches @oliviertassinari! handled in #40981

Add deprecations migration guide

2e776b7

DiegoAndai added docs Improvements or additions to the documentation package: material-ui Specific to @mui/material labels Jan 23, 2024

DiegoAndai self-assigned this Jan 23, 2024

Address reviewdog review

cf4d74b

DiegoAndai mentioned this pull request Jan 24, 2024

[codemod] Add accordion props deprecation #40771

Merged

1 task

DiegoAndai added 3 commits January 25, 2024 16:24

Improve copy and add placeholder links

c736429

Add links and reduce duplication

d1cce84

Add link in deprecated Accordion props to guide

43fb3c6

DiegoAndai marked this pull request as ready for review January 30, 2024 21:25

DiegoAndai requested a review from samuelsycamore January 30, 2024 21:27

DiegoAndai mentioned this pull request Jan 30, 2024

[material-ui] Standardize slots pattern and composed classes #40417

Open

samuelsycamore reviewed Jan 31, 2024

View reviewed changes

DiegoAndai and others added 2 commits January 31, 2024 14:20

Apply suggestions from code review

4cc8786

Co-authored-by: Sam Sycamore <[email protected]> Signed-off-by: Diego Andai <[email protected]>

Update file names and copy

a652ff4

DiegoAndai requested a review from samuelsycamore January 31, 2024 18:33

samuelsycamore approved these changes Feb 1, 2024

View reviewed changes

Replace regular space with non-breaking space

f8af7de

DiegoAndai force-pushed the deprecations-migration-guide branch 3 times, most recently from 196c2d5 to 5f99aa8 Compare February 5, 2024 21:12

trigger ci

46623cb

DiegoAndai force-pushed the deprecations-migration-guide branch from 5f99aa8 to 46623cb Compare February 6, 2024 12:28

DiegoAndai merged commit b3298b8 into mui:master Feb 6, 2024
21 checks passed

DiegoAndai deleted the deprecations-migration-guide branch February 6, 2024 12:42

DiegoAndai mentioned this pull request Feb 6, 2024

[material-ui][Backdrop] Deprecate TransitionComponent #40677

Merged

oliviertassinari reviewed Feb 6, 2024

View reviewed changes

DiegoAndai mentioned this pull request Feb 7, 2024

[material-ui][docs] Migrating from deprecated apis follow up #40981

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[material-ui][docs] Add deprecations migration guide #40767

[material-ui][docs] Add deprecations migration guide #40767

DiegoAndai commented Jan 23, 2024 •

edited

Loading

mui-bot commented Jan 23, 2024 •

edited

Loading

samuelsycamore left a comment

DiegoAndai commented Jan 31, 2024 •

edited

Loading

danilo-leal commented Feb 1, 2024

samuelsycamore commented Feb 1, 2024 •

edited

Loading

danilo-leal commented Feb 1, 2024

samuelsycamore commented Feb 1, 2024

samuelsycamore left a comment

oliviertassinari left a comment •

edited

Loading

oliviertassinari Feb 6, 2024 •

edited

Loading

oliviertassinari Feb 6, 2024 •

edited

Loading

oliviertassinari Feb 6, 2024 •

edited

Loading

oliviertassinari left a comment

oliviertassinari Feb 6, 2024 •

edited

Loading

DiegoAndai Feb 7, 2024

DiegoAndai commented Feb 7, 2024

		- TransitionComponent={CustomTransition}
		+ slots={{ transition: CustomTransition }}


		### TransitionProps

		The Accordion's `TransitionProps` was deprecated in favor of `slotProps.transition` ([Codemod](https://github.com/mui/material-ui/tree/master/packages/mui-codemod#accordion-props)):


		### TransitionComponent

		The Accordion's `TransitionComponent` was deprecated in favor of `slots.transition` ([Codemod](https://github.com/mui/material-ui/tree/master/packages/mui-codemod#accordion-props)):

[material-ui][docs] Add deprecations migration guide #40767

[material-ui][docs] Add deprecations migration guide #40767

Conversation

DiegoAndai commented Jan 23, 2024 • edited Loading

mui-bot commented Jan 23, 2024 • edited Loading

Netlify deploy preview

Bundle size report

samuelsycamore left a comment

Choose a reason for hiding this comment

DiegoAndai commented Jan 31, 2024 • edited Loading

danilo-leal commented Feb 1, 2024

samuelsycamore commented Feb 1, 2024 • edited Loading

danilo-leal commented Feb 1, 2024

samuelsycamore commented Feb 1, 2024

samuelsycamore left a comment

Choose a reason for hiding this comment

oliviertassinari left a comment • edited Loading

Choose a reason for hiding this comment

oliviertassinari Feb 6, 2024 • edited Loading

Choose a reason for hiding this comment

oliviertassinari Feb 6, 2024 • edited Loading

Choose a reason for hiding this comment

oliviertassinari Feb 6, 2024 • edited Loading

Choose a reason for hiding this comment

oliviertassinari left a comment

Choose a reason for hiding this comment

oliviertassinari Feb 6, 2024 • edited Loading

Choose a reason for hiding this comment

DiegoAndai Feb 7, 2024

Choose a reason for hiding this comment

DiegoAndai commented Feb 7, 2024

DiegoAndai commented Jan 23, 2024 •

edited

Loading

mui-bot commented Jan 23, 2024 •

edited

Loading

DiegoAndai commented Jan 31, 2024 •

edited

Loading

samuelsycamore commented Feb 1, 2024 •

edited

Loading

oliviertassinari left a comment •

edited

Loading

oliviertassinari Feb 6, 2024 •

edited

Loading

oliviertassinari Feb 6, 2024 •

edited

Loading

oliviertassinari Feb 6, 2024 •

edited

Loading

oliviertassinari Feb 6, 2024 •

edited

Loading